{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to atomman: prototype loading\n",
    "\n",
    "__Lucas M. Hale__, [lucas.hale@nist.gov](mailto:lucas.hale@nist.gov?Subject=ipr-demo), _Materials Science and Engineering Division, NIST_.\n",
    "    \n",
    "[Disclaimers](http://www.nist.gov/public_affairs/disclaimer.cfm) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Introduction<a id='section1'></a>\n",
    "\n",
    "The crystal_prototype records found in the NIST Interatomic Potentials Repository database (https://potentials.nist.gov/) define a number of unit cells for standard crystal prototypes. The 'prototype' load option allows Systems to be constructed based on the information in these records.  The information can be loaded either from a local copy of the database or the remote database.  \n",
    "\n",
    "*Updated version 1.4.0.* Query parameters and database options updated to be in line with potentials version 0.3.0."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Library Imports**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "atomman version = 1.4.0\n",
      "Notebook executed on 2021-08-04\n"
     ]
    }
   ],
   "source": [
    "# Standard Python libraries\n",
    "import datetime\n",
    "\n",
    "# http://www.numpy.org/\n",
    "import numpy as np\n",
    "\n",
    "import atomman as am\n",
    "import atomman.unitconvert as uc\n",
    "\n",
    "# Show atomman version\n",
    "print('atomman version =', am.__version__)\n",
    "\n",
    "# Show date of Notebook execution\n",
    "print('Notebook executed on', datetime.date.today())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. atomman.load('prototype')<a id='section2'></a>\n",
    "\n",
    "Accesses the potentials database to retrieve a crystal_prototype record and generate a unit cell System based on it.\n",
    "\n",
    "Query parameters\n",
    "- __name__ (*str or list, optional*) Record names to search for.  These should be the same values as id.\n",
    "- __id__ (*str or list, optional*) Prototype ID(s) to search for.  These are unique identifiers for each prototype based on comm.\n",
    "- __key__ (*str or list, optional*) UUID4 key(s) to search for.  Each entry has a unique random-generated UUID4 key.\n",
    "- __commonname__ (*str or list, optional*) Common name(s) to limit the search by.\n",
    "- __prototype__ (*str or list, optional*) Prototype identifying composition(s) to limit the search by.\n",
    "- __pearson__ (*str or list, optional*) The Pearson symbol(s) to limit the search by.\n",
    "- __strukturbericht__ (*str or list, optional*) The strukturbericht identifier(s) to limit the search by.\n",
    "- __sg_number__ (*int or list, optional*) The space group number(s) to limit the search by.\n",
    "- __sg_hm__ (*str or list, optional*) The space group Hermann-Maguin identifier(s) to limit the search by.\n",
    "- __sg_schoenflies__ (*str or list, optional*) The space group Schoenflies identifier(s) to limit the search by.\n",
    "\n",
    "Modification parameters\n",
    "\n",
    "- __a__ (*float, optional*) The a lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __b__ (*float, optional*) The b lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __c__ (*float, optional*) The c lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __alpha__ (*float, optional*) The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __beta__ (*float, optional*) The beta lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __gamma__ (*gamma, optional*) The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype's crystal family, and if all other unique lattice parameters are given.\n",
    "- __symbols__ (*tuple, optional*) Allows the list of element symbols to be assigned during loading.\n",
    "\n",
    "Database option parameters\n",
    "\n",
    "- __database__ (*atomman.library.Database, optional*) A pre-defined Database object to use.  If not given, will initialize a new Database object.  Passing in a database can save time if multiple calls are made for the same record type. \n",
    "- __localpath__ (*str, optional*) The local library path to use when initializing a new Database.  IF not given, will use the default localpath.  Ignored if database is given. \n",
    "- __local__ (*bool, optional*) Indicates if the Database object is to look for local records.  Default is True.  Ignored if database is given.\n",
    "- __remote__ (*bool, optional*) Indicates if the Database object is to look for remote records.  Default is True.  Ignored if database is given.\n",
    "- __prompt__ (*bool, optional*) If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found.  If prompt=False, then an error will be thrown if multiple matches are found.\n",
    "- __refresh_cache__ (*bool, optional*) If the local database is of style \"local\", indicates if the metadata cache file is to be refreshed.  If False, metadata for new records will be added but the old record metadata fields will not be updated.  If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.\n",
    "- __verbose__ (*bool, optional*) If True, info messages will be printed during operations.  Default value is False.\n",
    "\n",
    "Returns\n",
    "    \n",
    "- __system__ (*atomman.System*) The system object generated from the crystal prototype."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1. Query parameters\n",
    "\n",
    "Prototypes can be selected based on a number of different ids."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 1.000,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  1.000,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  1.000]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = (None,)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   0.500 |   0.500\n",
      "      2 |       1 |   0.500 |   0.000 |   0.500\n",
      "      3 |       1 |   0.500 |   0.500 |   0.000\n"
     ]
    }
   ],
   "source": [
    "ucell = am.load(\"prototype\", id='A1--Cu--fcc')\n",
    "print(ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, if you give no extra keyword arguments you will get a prompt selection of all prototypes in the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Multiple matching record retrieved from local\n",
      "1 A1--Cu--fcc\n",
      "2 A15--Cr3Si\n",
      "3 A15--beta-W\n",
      "4 A2--W--bcc\n",
      "5 A3'--alpha-La--double-hcp\n",
      "6 A3--Mg--hcp\n",
      "7 A4--C--dc\n",
      "8 A5--beta-Sn\n",
      "9 A6--In--bct\n",
      "10 A7--alpha-As\n",
      "11 Ah--alpha-Po--sc\n",
      "12 B1--NaCl--rock-salt\n",
      "13 B2--CsCl\n",
      "14 B3--ZnS--cubic-zinc-blende\n",
      "15 C1--CaF2--fluorite\n",
      "16 D0_3--BiF3\n",
      "17 L1_0--AuCu\n",
      "18 L1_2--AuCu3\n",
      "19 L2_1--AlCu2Mn--heusler\n"
     ]
    },
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "Please select one: 1\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 1.000,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  1.000,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  1.000]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = (None,)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   0.500 |   0.500\n",
      "      2 |       1 |   0.500 |   0.000 |   0.500\n",
      "      3 |       1 |   0.500 |   0.500 |   0.000\n"
     ]
    }
   ],
   "source": [
    "ucell = am.load(\"prototype\")\n",
    "print(ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2. Modification parameters\n",
    "\n",
    "The nature of a crystal prototype is that it is stripped of element-specific information: there are no elements/symbols assigned to the atom types and all lattice constants are scaled based on a=1 and the \"ideal\" ratios for the reference crystal.  Because of this, the lattice constants and symbols can be set within the load method.\n",
    "\n",
    "__NOTE__: The allowed lattice constants for this method depend on the independent lattice constants associated with the prototype's crystal family (cubic, hexagonal, etc.).  Either all or none of the independent lattice constants can be set during load. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 4.050,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  4.050,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  4.050]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = ('Al',)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   2.025 |   2.025\n",
      "      2 |       1 |   2.025 |   0.000 |   2.025\n",
      "      3 |       1 |   2.025 |   2.025 |   0.000\n"
     ]
    }
   ],
   "source": [
    "ucell = am.load(\"prototype\", 'A1--Cu--fcc', a=4.05, symbols='Al')\n",
    "print(ucell)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 2.950,  0.000,  0.000]\n",
      "bvect =  [-1.475,  2.555,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  4.700]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 2\n",
      "natypes = 1\n",
      "symbols = ('Ti',)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   1.703 |   2.350\n"
     ]
    }
   ],
   "source": [
    "ucell = am.load(\"prototype\", 'A3--Mg--hcp', a=2.95, c=4.70, symbols='Ti')\n",
    "print(ucell)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
